The Chat Rooms Widget

The Chat Rooms widget provides a direct link from a Connections Community to Sametime Advanced persistent chat rooms. In a chat room, users can participate in a live conversation with other users. The chat room conversation is persisted, and can be viewed or revived at a later time. The Chat Rooms widget provides a list of chat rooms which have been created for the specific Community. Clicking a chat room link redirects the user to that chat room on the Sametime Advanced web user interface. Chat rooms can be created using the widget, which will be directly associated with the Community.

How does the Chat Rooms Widget work?

The widget sends HTTP requests to the Sametime Advanced server which are handled by its REST API. The API allows the widget to retrieve chat room information and to create chat rooms from within the Community page. This provides an integration between Connections and the Sametime Advanced application.

Supported versions

Enabling Single Sign-On

The Sametime Advanced API requires authentication before releasing data, therefore, you must enable single sign-on between Connections and the Sametime Advanced Server. Complete these procedures to enable single sign-on:

1. Export LTPA tokens from the Sametime Advanced server.
2. Import those LTPA tokens into the Connections server.
3. Enable single sign-on.
4. Configure the LDAP on WebSphere.

For detailed instructions to enable single sign-on, see this topic: Configuring single sign-on with an LTPA token on IBM WebSphere and IBM Domino prlatforms.

Installation

Prerequisites

Install these servers prior to completing this procedure:

• IBM Connections server with Communities, News, Common, WidgetContainer and Profiles applications
• IBM Sametime Advanced Server

Unpacking the widget files to the Connections server

The widget files are attachments to this wiki page. Download the widget files to the computer hosting the Connections server.

Extract the widget files.

After the widget files are downloaded and extracted, complete these steps:

Configuring the Sametime Advanced web user interface folders

Use the Web UI to configure the Sametime Advanced folders to ensure there is no interference in the communication between Connections and the Sametime Advanced Server.

When the widget is added to a Community, the widget creates a folder to store all chat rooms for that Community. A folder must be manually created to store all of these Community folders.

Retrieving the globalFolderId value

The globalFolderId value is required to configure the widget. Retrieve the globalFolderId value from the Sametime Advanced Server web user interface using a developer tool on a browser, such as Firefox.

1. In Sametime Advanced, click the All Chat Rooms tab.
2. Right-click the link to the folder that you created in the Configuring Sametime Advanced folders procedure.
3. Click Inspect Element. A link and folder ID are displayed, for example, 
4. Make note of the folder ID, not including "link," to use later for configuration.

Adding the widget to the widget definition file

Instructions for modifying the widgets-config.xml file are located here: IBM - Using the widgets-config.xml file for Communities.

You must insert a definition for the Chat Rooms widget into the widgets-config.xml file. Use this definition, but note that you need to customize some values. See the table at the end of this definition for a list of values that require customizing.

Note: Modify the url value according to your own configuration.

 <widgetDef defId="Chat Rooms" primaryWidget="false" modes="view"

url="/communities/nav/common/ChatRoomsWidget.xml" uniqueInstance="true"

iconUrl="/communities/nav/common/chat-icon.png">

<itemSet>

<item name="sametimeAdvancedUrl" value="http://sametimeadvanced.ibm.com:9080" />

<item name="globalFolderId" value="20130329-1212-5521-8958-000000000000" />

<item name="globalFolderName" value="Community Chat Rooms" />

<item name="sortChatRoomsBy" value="unreadLineCount" />

<item name="widgetFilePath" value="/communities/nav/common/" />

</itemSet>

</widgetDef>  

Configuring the Ajax proxy
The Ajax proxy allows requests to be made across domains. Since the Sametime Advanced application resides on its own server, not on the Connections server, requests should be made through the Ajax proxy. The WebSphere Application Server contains a modifiable proxy configuration file, proxy-config.tpl. To modify the file, see this procedure: Configuring the Ajax proxy.

The proxy must allow the actions, cookies, and headers as shown in the text below.

Note: You must modify the 'url' value to reflect your own configuration.

 <proxy:mapping contextpath="/http/*"/>

<proxy:mapping contextpath="/https/*"/>

<proxy:policy url="[protocol]://[sametime_advanced_domain]:[port_number]/*" acf="none">

<proxy:actions>

<proxy:method>GET</proxy:method>

<proxy:method>HEAD</proxy:method>

<proxy:method>POST</proxy:method>

<proxy:method>PUT</proxy:method>

<proxy:method>DELETE</proxy:method>

</proxy:actions>

<proxy:cookies>

<proxy:cookie>LtpaToken</proxy:cookie>

<proxy:cookie>LtpaToken2</proxy:cookie>

<proxy:cookie>JSESSIONID</proxy:cookie>

</proxy:cookies>

<proxy:headers>

<proxy:header>User-Agent</proxy:header>

<proxy:header>Accept.*</proxy:header>

<proxy:header>Content.*</proxy:header>

<proxy:header>Authorization.*</proxy:header>

<proxy:header>If-.*</proxy:header>

<proxy:header>Pragma</proxy:header>

<proxy:header>Cache-Control</proxy:header>

<proxy:header>X-Update-Nonce</proxy:header>

<proxy:header>WWW-Authenticate.*</proxy:header>

<proxy:header>Access.*</proxy:header>

</proxy:headers>

</proxy:policy> 

To allow Community members to access the Community's chat rooms, a separate module must synchronize the membership. Install this module, ChatRoomsMembershipSynchroniser.jar, on the WebSphere Integrated Solutions Console.

Creating the shared library

For instructions on how to create a shared library, see the article: Creating shared libraries.

In the Classpath field, enter the name of the jar file, including the path
${WAS_INSTALL_ROOT}/optionalLibraries/Chat Rooms SPI/ChatRoomsMembershipSynchroniser.jar

Note: ${WAS_INSTALL_ROOT} variable is configured by default, and is equivalent to C:\IBM\WebSphere\AppServer.

Deploying the event handler on the Connections server

Instructions to deploy the event handler are described in this article: Deploying an event handler.

Adding the shared library to the News module

1. Log in to the Integrated Solutions Console as the WebSphere administrator.
2. In the navigation tree, click Applications->Application Types->WebSphere enterprise applications->News->References->Shared library references.
3. Select News.
4. Click Reference shared libraries.
5. Select the shared library you created.
6. Click the right arrow to add the shared library to the Selected field.
7. Click OK.
8. Click OK again.
9. Click Save directly to the master configuration.

Registering the event handler with Connections:

1. Open the events-config.xml file, usually located at :
   [WAS_HOME]/profiles/AppSrv01/config/cells/[CELL]/LotusConnections-config ).
2. Find the tag .
3. Within that tag, add this code:

 <postHandler enabled="true" invoke="ASYNC" name="ChatRoomsMembershipSynchroniser" class="chatrooms.ChatRoomsMembershipSynchroniser">

<subscriptions>

<subscription source="COMMUNITIES" type="MEMBERSHIP" eventName="*"/>

</subscriptions>

</postHandler>

Supplying Credentials

The membership synchronizer makes requests to the Sametime Advanced Server on behalf of a user, therefore, it must use credentials. Use the Java Authentication and Authorization Service for these credentials.

Complete these steps to create a new login resource.

1. Log into the Integrated Solutions Console as the WebSphere administrator on the Connections server.
2. In the navigation tree, click Security->Global security->Java Authentication and Authorization Service->J2C authentication data.
3. For compatibility with earlier releases, deselect Prefix new alias names with the node name of the cell. If you are deselecting this, save the changes, synchronize the appropriate node, and restart the application server, before continuing to step 4.
4. Click New.
5. In the alias field, enter sametimeAdvancedAdmin. This is case-sensitive and must be this exact value.
6. Enter the username and password for the master user of Sametime Advanced.
7. Click OK, resynchronize the appropriate node, and restart the application server.

Now that the master credentials are configured, you supply the Membership Synchronizer with property values that are unique to your setup of Connections and the Sametime Advanced Server.

Use WebSphere variables to include the properties in the membership synchronizer.

1. Log in to the Integrated Solutions Console as the WebSphere administrator.
2. In the navigation tree, click Environment->WebSphere variables.
3. Select the appropriate scope from the drop-down list, for the variables. See the page's help for more information on scope.
4. Click New.
5. Set the Name/Values based on the table below.
6. Save the changes, resynchronize the appropriate node, and restart the application server.

Note: In WebSphere, the node must be fully resynchronized, and the WebSphere application server must be restarted for all changes to take effect.

Installation Troubleshooting

Internet Explorer in protected mode

Using Internet Explorer in protected mode causes single sign-on to break between Connections and the Sametime Advanced Server. Members are prompted to log in when attempting to view a chat room, and owners can not create a new chat room. To resolve the problem, turn off protected mode in Internet Explorer.

Chat rooms created using the Sametime Advanced Server UI

Chat rooms are tightly coupled to the concept of a Community-owned chat room. Creating, modifying, or deleting a chat room using the Sametime Advanced UI does not guarantee the stability of the chat rooms within the widget. To reset a widget and remove its chat rooms, go to the Sametime Advanced user interface, delete the folder for the Community, and remove the widget from the Community page. When you re-add the widget, no chat rooms remain.

Chat rooms created using the Sametime Advanced user interface appear in the widget, but do not have synchronized membership. Members are not authorized to access the chat room.

Debugging the membership synchronizer

When the membership synchronizer fails, an error message is logged to the log files. An administrator can view these error messages at: [WAS_HOME]/profiles/AppSrv01/logs/[SERVER_NAME]/SystemOut.log.

Using the Chat Rooms Widget

You must be the Community owner to create a chat room.

Create a chat room by completing these steps:

1. Click the Create a Chat Room link.
2. Enter a name for the new chat room.
3. Enter a description for the new chat room.
4. Click Create.

Limitations and Known Issues

Incorrect unread lines value

In this scenario, a user may see an incorrect value for the number of unread lines in a chat room:

A hotfix should be available for Sametime Advanced.

No group support

The widget does not support group synchronization between Communities and chat rooms.

Editing the Community Name

When the widget is functioning correctly, removing and re-adding the widget to the Community page restores the list of chat rooms. To prevent the widget from restoring the list of chat rooms, complete these steps:

1. Create chat rooms in the widget.
2. Remove the widget.
3. Rename the Community.
4. Re-add the widget to the page.

The chat rooms are not restored because the widget retrieves the list of chat rooms based on the Community name. If the widget is not on the page when the Community is renamed, it is not aware of the name change, and can not retrieve the chat room list.

No full page mode

The widget only supports a view mode; it does not support a full page mode.

Changing the widget sort order

The sort order of the chat rooms in the widget is defined by the sortChatRoomsBy value in the widgets-config.xml file, on the Connections server. If you update the sort order, all Communities which had previously added the widget will not sort by the updated sort order. To activate the updated sort order, you must remove the widget from the Community, and re-add it to the page.

Error Code Reference

001

The Sametime Advanced folder to store the Community chat rooms could not be created. The REST (POST) request to the Sametime Advanced Server failed.
Possible causes:

• the Sametime Advanced server/applications may be inactive.
• the sametimeAdvancedDomain value is incorrect in the widgets-config.xml file.
• the globalFolderId value is incorrect in the widgets-config.xml file.
• the Ajax proxy was configured incorrectly.

002
The folder failed to update in Sametime Advanced. The REST (PUT) request to the Sametime Advanced Server failed.
Possible causes:

• the Sametime Advanced server/applications may be inactive.
• the sametimeAdvancedDomain value is incorrect in the widgets-config.xml file.
• the Ajax proxy was configured incorrectly.

003
The regular expression failed to get the folder id. When the folder is created on Sametime Advanced, which stores the Community's chat rooms, the folder's id is retrieved using the Community's name. A regular expression is used to extract the folder id from the response. This error code appears if this action fails.
Possible causes:

• the Sametime Advanced server/applications may be inactive.
• the sametimeAdvancedDomain value is incorrect in the widgets-config.xml file.
• the globalFolderId value is incorrect in the widgets-config.xml file.
• the Sametime Advanced API has changed the pattern for which it delivers its data.

004
The request failed to get the folder id. The REST (GET) request to the Sametime Advanced Server failed.
Possible causes:

• the Sametime Advanced server/applications may be inactive.
• the sametimeAdvancedDomain value is incorrect in the widgets-config.xml file.
• the globalFolderId value is incorrect in the widgets-config.xml file.
• the Ajax proxy was configured incorrectly.

005
The request failed to get the members of the Community. The REST (GET) request to the Communities API failed.
Possible causes:

• the Communities API is not returning the list of members.

006
The request failed to get the chat rooms. The REST (GET) request to the Sametime Advanced Server failed.
Possible causes:

• You are no longer an 'owner' of the Community.
• the Sametime Advanced server/applications may be inactive.
• the sametimeAdvancedDomain value is incorrect in the widgets-config.xml file.
• the globalFolderName value is incorrect in the widgets-config.xml file.
• the Ajax proxy was configured incorrectly.

007
The request failed to create the chat room. The REST (POST) request to the Sametime Advanced Server failed.
Possible causes:

• the Sametime Advanced server/applications may be inactive.
• the sametimeAdvancedDomain value is incorrect in the widgets-config.xml file.
• the folderId value is incorrect for the Community's folder.
• the Ajax proxy was configured incorrectly.

008
The request failed to get the chat rooms. The REST (GET) request to the Sametime Advanced Server failed after the widget has been re-added to the Community.
Possible causes:

• the Sametime Advanced server/applications may be inactive.
• the sametimeAdvancedDomain value is incorrect in the widgets-config.xml file.
• the globalFolderId value is incorrect in the widgets-config.xml file.
• the Ajax proxy was configured incorrectly.

009
The regular expression failed to find a chat room id or active user count or unread line count.
Possible causes:

• the Sametime Advanced server/applications may be inactive.
• the Sametime Advanced API has changed the pattern for which it delivers its data.

010
You are no longer authorized to create a chat room.
Possible causes:

• You were previously an owner of the Community, and now you are a member.

403
Failed to send a request through the Ajax proxy.
Possible causes:

1. The URL value in the proxy policy is incorrect.
2. The incorrect proxy policy is being used.

Troubleshooting:
To test if the Ajax proxy is the cause of the 403 error code, move the policy in the file, so that it is the first policy. Then change the URL value to "*" - this means that it accepts all URLs for cross-domain requests. In WebSphere, the node must be fully re-synchronised and the application server must be restarted, for changes to take effect.

Solution:
Use the Sametime Advanced server URL with an asterisk at the end. Example: url="http://myAdvancedServer.ibm.com:9080/*".

Other error codes
You may see other error codes which are standard HTTP status codes. Open the browser's developer tools to investigate these issues.